home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-Native.exe / {app} / include / elements / CEGUITooltip.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-02  |  12.6 KB  |  362 lines
  1. /************************************************************************
  2.     filename:   CEGUITooltip.h
  3.     created:    21/2/2005
  4.     author:     Paul D Turner
  5. *************************************************************************/
  6. /*************************************************************************
  7.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  8.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  9.  
  10.     This library is free software; you can redistribute it and/or
  11.     modify it under the terms of the GNU Lesser General Public
  12.     License as published by the Free Software Foundation; either
  13.     version 2.1 of the License, or (at your option) any later version.
  14.  
  15.     This library is distributed in the hope that it will be useful,
  16.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  17.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18.     Lesser General Public License for more details.
  19.  
  20.     You should have received a copy of the GNU Lesser General Public
  21.     License along with this library; if not, write to the Free Software
  22.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23. *************************************************************************/
  24. #ifndef _CEGUITooltip_h_
  25. #define _CEGUITooltip_h_
  26.  
  27. #include "CEGUIWindow.h"
  28. #include "elements/CEGUITooltipProperties.h"
  29.  
  30. #if defined(_MSC_VER)
  31. #    pragma warning(push)
  32. #    pragma warning(disable : 4251)
  33. #endif
  34.  
  35. // Start of CEGUI namespace section
  36. namespace CEGUI
  37. {
  38.     /*!
  39.     \brief
  40.         Base class for Tooltip widgets.
  41.         
  42.         The Tooltip class shows a simple pop-up window around the mouse position
  43.         with some text information.  The tool-tip fades in when the user hovers
  44.         with the mouse over a window which has tool-tip text set, and then fades
  45.         out after some pre-set time.
  46.  
  47.     \note
  48.         For Tooltip to work properly, you must specify a default tool-tip widget
  49.         type via System::setTooltip, or by setting a custom tool-tip object for
  50.         your Window(s).  Additionally, you need to ensure that time pulses are
  51.         properly passed to the system via System::injectTimePulse.
  52.     */
  53.     class CEGUIEXPORT Tooltip : public Window
  54.     {
  55.     public:
  56.         /*************************************************************************
  57.             Constants
  58.         *************************************************************************/
  59.         static const String EventNamespace;                 //!< Namespace for global events
  60.         static const String EventHoverTimeChanged;          //!< Event fired when the hover timeout gets changed.
  61.         static const String EventDisplayTimeChanged;        //!< Event fired when the display timeout gets changed.
  62.         static const String EventFadeTimeChanged;           //!< Event fired when the fade timeout gets changed.
  63.         static const String EventTooltipActive;             //!< Event fired when the tooltip is about to get activated.
  64.         static const String EventTooltipInactive;           //!< Event fired when the tooltip has been deactivated.
  65.  
  66.         /************************************************************************
  67.             Object Construction and Destruction
  68.         ************************************************************************/
  69.         /*!
  70.         \brief
  71.             Constructor for the Tooltip base class constructor
  72.          */
  73.         Tooltip(const String& type, const String& name);
  74.  
  75.         /*!
  76.         \brief
  77.             Destructor for the Tooltip base class.
  78.          */
  79.         ~Tooltip(void);
  80.  
  81.         /************************************************************************
  82.             Public interface
  83.         ************************************************************************/
  84.         /*!
  85.         \brief
  86.             Sets the target window for the tooltip.  This used internally to manage tooltips, you
  87.             should not have to call this yourself.
  88.  
  89.         \param wnd
  90.             Window object that the tooltip should be associated with (for now).
  91.  
  92.         \return
  93.             Nothing.
  94.          */
  95.         void setTargetWindow(Window* wnd);
  96.  
  97.         /*!
  98.         \brief
  99.             return the current target window for this Tooltip.
  100.  
  101.         \return
  102.             Pointer to the target window for this Tooltip or 0 for none.
  103.         */
  104.         const Window* getTargetWindow();
  105.  
  106.         /*!
  107.         \brief
  108.             Resets the timer on the tooltip when in the Active / Inactive states.  This is used internally
  109.             to control the tooltip, it is not normally necessary to call this method yourself.
  110.  
  111.         \return
  112.             Nothing.
  113.          */
  114.         void resetTimer(void);
  115.  
  116.         /*!
  117.         \brief
  118.             Return the number of seconds the mouse should hover stationary over the target window before
  119.             the tooltip gets activated.
  120.  
  121.         \return
  122.             float value representing a number of seconds.
  123.          */
  124.         float getHoverTime(void) const;
  125.  
  126.         /*!
  127.         \brief
  128.             Set the number of seconds the tooltip should be displayed for before it automatically
  129.             de-activates itself.  0 indicates that the tooltip should never timesout and auto-deactivate.
  130.  
  131.         \param seconds
  132.             float value representing a number of seconds.
  133.  
  134.         \return
  135.             Nothing.
  136.          */
  137.         void setDisplayTime(float seconds);
  138.  
  139.         /*!
  140.         \brief
  141.             Return the number of seconds that should be taken to fade the tooltip into and out of
  142.             visibility.
  143.  
  144.         \return
  145.             float value representing a number of seconds.
  146.          */
  147.         float getFadeTime(void) const;
  148.  
  149.         /*!
  150.         \brief
  151.             Set the number of seconds the mouse should hover stationary over the target window before
  152.             the tooltip gets activated.
  153.  
  154.         \param seconds
  155.             float value representing a number of seconds.
  156.  
  157.         \return
  158.             Nothing.
  159.          */
  160.         void setHoverTime(float seconds);
  161.  
  162.         /*!
  163.         \brief
  164.             Return the number of seconds the tooltip should be displayed for before it automatically
  165.             de-activates itself.  0 indicates that the tooltip never timesout and auto-deactivates.
  166.  
  167.         \return
  168.             float value representing a number of seconds.
  169.          */
  170.         float getDisplayTime(void) const;
  171.  
  172.         /*!
  173.         \brief
  174.             Set the number of seconds that should be taken to fade the tooltip into and out of
  175.             visibility.
  176.  
  177.         \param seconds
  178.             float value representing a number of seconds.
  179.  
  180.         \return
  181.             Nothing.
  182.          */
  183.         void setFadeTime(float seconds);
  184.  
  185.         // 
  186.         /*!
  187.         \brief
  188.             Causes the tooltip to position itself appropriately.
  189.  
  190.         \return
  191.             Nothing.
  192.         */
  193.         void positionSelf(void);
  194.  
  195.     protected:
  196.         /*************************************************************************
  197.             Implementation Methods
  198.         *************************************************************************/
  199.         /*!
  200.         \brief
  201.             Add ScrollablePane specific events
  202.         */
  203.         void addTooltipEvents(void);
  204.  
  205.         // methods to perform processing for each of the widget states
  206.         void doActiveState(float elapsed);
  207.         void doInactiveState(float elapsed);
  208.         void doFadeInState(float elapsed);
  209.         void doFadeOutState(float elapsed);
  210.  
  211.         // methods to switch widget states
  212.         void switchToInactiveState(void);
  213.         void switchToActiveState(void);
  214.         void switchToFadeInState(void);
  215.         void switchToFadeOutState(void);
  216.  
  217.  
  218.         /*!
  219.         \brief
  220.             Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
  221.  
  222.         \param class_name
  223.             The class name that is to be checked.
  224.  
  225.         \return
  226.             true if this window was inherited from \a class_name. false if not.
  227.         */
  228.         virtual bool    testClassName_impl(const String& class_name) const
  229.         {
  230.             if (class_name==(const utf8*)"Tooltip")    return true;
  231.             return Window::testClassName_impl(class_name);
  232.         }
  233.  
  234.         /*!
  235.         \brief
  236.             Return the size of the area that will be occupied by the tooltip text, given
  237.             any current formatting options.
  238.  
  239.         \return
  240.             Size object describing the size of the rendered tooltip text in pixels.
  241.         */
  242.         virtual Size getTextSize() const;
  243.  
  244.         /*************************************************************************
  245.             Event triggers
  246.         *************************************************************************/
  247.         /*!
  248.         \brief
  249.             Event trigger method called when the hover timeout gets changed.
  250.  
  251.         \param e
  252.             WindowEventArgs object.
  253.  
  254.         \return
  255.             Nothing.
  256.         */
  257.         virtual void onHoverTimeChanged(WindowEventArgs& e);
  258.  
  259.         /*!
  260.         \brief
  261.             Event trigger method called when the display timeout gets changed.
  262.  
  263.         \param e
  264.             WindowEventArgs object.
  265.  
  266.         \return
  267.             Nothing.
  268.         */
  269.         virtual void onDisplayTimeChanged(WindowEventArgs& e);
  270.  
  271.         /*!
  272.         \brief
  273.             Event trigger method called when the fade timeout gets changed.
  274.  
  275.         \param e
  276.             WindowEventArgs object.
  277.  
  278.         \return
  279.             Nothing.
  280.         */
  281.         virtual void onFadeTimeChanged(WindowEventArgs& e);
  282.  
  283.         /*!
  284.         \brief
  285.             Event trigger method called just before the tooltip becomes active.
  286.  
  287.         \param e
  288.             WindowEventArgs object.
  289.  
  290.         \return
  291.             Nothing.
  292.         */
  293.         virtual void onTooltipActive(WindowEventArgs& e);
  294.  
  295.         /*!
  296.         \brief
  297.             Event trigger method called just after the tooltip is deactivated.
  298.  
  299.         \param e
  300.             WindowEventArgs object.
  301.  
  302.         \return
  303.             Nothing.
  304.         */
  305.         virtual void onTooltipInactive(WindowEventArgs& e);
  306.  
  307.  
  308.         /************************************************************************
  309.             Overridden from Window.
  310.         ************************************************************************/
  311.         void updateSelf(float elapsed);
  312.         void onMouseEnters(MouseEventArgs& e);
  313.         void onTextChanged(WindowEventArgs& e);
  314.  
  315.         /************************************************************************
  316.             Enumerations
  317.         ************************************************************************/
  318.         /*!
  319.         \brief
  320.             states for tooltip
  321.          */
  322.         enum TipState
  323.         {
  324.             Inactive,   //!< Tooltip is currently inactive.
  325.             Active,     //!< Tooltip is currently displayed and active.
  326.             FadeIn,     //!< Tooltip is currently transitioning from Inactive to Active state.
  327.             FadeOut     //!< Tooltip is currently transitioning from Active to Inactive state.
  328.         };
  329.  
  330.         /************************************************************************
  331.             Data fields
  332.         ************************************************************************/
  333.         TipState    d_state;        //!< Current tooltip state.
  334.         float       d_elapsed;      //!< Used to track state change timings
  335.         const Window* d_target;     //!< Current target Window for this Tooltip.
  336.         float       d_hoverTime;    //!< tool-tip hover time (seconds mouse must stay stationary before tip shows).
  337.         float       d_displayTime;  //!< tool-tip display time (seconds that tip is showsn for).
  338.         float       d_fadeTime;     //!< tool-tip fade time (seconds it takes for tip to fade in and/or out).
  339.  
  340.     private:
  341.         /*************************************************************************
  342.             Static Properties for this class
  343.         *************************************************************************/
  344.         static TooltipProperties::HoverTime      d_hoverTimeProperty;
  345.         static TooltipProperties::DisplayTime    d_displayTimeProperty;
  346.         static TooltipProperties::FadeTime       d_fadeTimeProperty;
  347.  
  348.         /*************************************************************************
  349.             Private methods
  350.         *************************************************************************/
  351.         void addTooltipProperties(void);
  352.     };
  353.  
  354. } // End of  CEGUI namespace section
  355.  
  356.  
  357. #if defined(_MSC_VER)
  358. #    pragma warning(pop)
  359. #endif
  360.  
  361. #endif  // end of guard _CEGUITooltip_h_
  362.